home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kspell.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  16.5 KB  |  569 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 1997 David Sweet <dsweet@kde.org>
  3.    Copyright (C) 2003 Zack Rusin <zack@kde.org>
  4.  
  5.    This library is free software; you can redistribute it and/or
  6.    modify it under the terms of the GNU Library General Public
  7.    License version 2 as published by the Free Software Foundation.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19. #ifndef __KSPELL_H__
  20. #define __KSPELL_H__
  21.  
  22. #include "ksconfig.h"
  23.  
  24. #include <qobject.h>
  25. #include <qstringlist.h>
  26. #include <qstring.h>
  27. #include <kdelibs_export.h>
  28.  
  29. class QTextCodec;
  30. class KProcIO;
  31. class KProcess;
  32. class KSpellDlg;
  33.  
  34. /**
  35.  * %KDE Spellchecker
  36.  *
  37.  * A %KDE programmer's interface to International ISpell 3.1, ASpell,
  38.  * HSpell and ZPSpell..
  39.  * A static method, modalCheck() is provided for convenient
  40.  *  access to the spellchecker.
  41.  *
  42.  * @author David Sweet <dsweet@kde.org>
  43.  * @see KSpellConfig, KSyntaxHighlighter
  44.  */
  45.  
  46. class KDEUI_EXPORT KSpell : public QObject
  47. {
  48.   Q_OBJECT
  49.  
  50. public:
  51.  
  52.   /**
  53.    * Possible states of the spell checker.
  54.    *
  55.    * @li @p Starting - After creation of KSpell.
  56.    * @li @p Running - After the ready signal has been emitted.
  57.    * @li @p Cleaning - After cleanUp() has been called.
  58.    * @li @p Finished - After cleanUp() has been completed.
  59.    *
  60.    * The following error states exist:
  61.    *
  62.    * @li @p Error -  An error occurred in the @p Starting state.
  63.    * @li @p Crashed - An error occurred in the @p Running state.
  64.    **/
  65.   enum spellStatus { Starting = 0, Running, Cleaning, Finished, Error, Crashed, FinishedNoMisspellingsEncountered };
  66.  
  67.   /**
  68.    * These are possible types of documents which the spell checker can check.
  69.    *
  70.    * @li @p Text  - The default type, checks every word
  71.    * @li @p HTML  - For HTML/SGML/XML documents, will skip the tags,
  72.    * @li @p TeX   - For TeX/LaTeX documents, will skip commands,
  73.    * @li @p Nroff - For nroff/troff documents.
  74.    *
  75.    * Please note that not every option is supported on every type of
  76.    * checker (e.g. ASpell doesn't support Nroff). In case a type
  77.    * of a document is not supported the default Text option will
  78.    * be used.
  79.    */
  80.   enum SpellerType { Text = 0, HTML, TeX, Nroff };
  81.  
  82.   /**
  83.    * Starts the spellchecker.
  84.    *
  85.    * KSpell emits ready() when it has verified that
  86.    * ISpell/ASpell is working properly. Pass the name of a slot -- do not pass zero!
  87.    * Be sure to call cleanUp() when you are done with KSpell.
  88.    *
  89.    * If KSpell could not be started correctly, death() is emitted.
  90.    *
  91.    * @param parent      Parent of KSpellConfig dialog..
  92.    * @param caption     Caption of KSpellConfig dialog.
  93.    * @param receiver    Receiver object for the ready(KSpell *) signal.
  94.    * @param slot        Receiver's slot, will be connected to the ready(KSpell *) signal.
  95.    * @param kcs         Configuration for KSpell.
  96.    * @param progressbar Indicates if progress bar should be shown.
  97.    * @param modal       Indicates modal or non-modal dialog.
  98.    */
  99.   KSpell(QWidget *parent, const QString &caption,
  100.      QObject *receiver, const char *slot, KSpellConfig *kcs=0,
  101.      bool progressbar = true, bool modal = false);
  102.  
  103.   /**
  104.    * Starts the spellchecker.
  105.    *
  106.    * KSpell emits ready() when it has verified that
  107.    * ISpell/ASpell is working properly. Pass the name of a slot -- do not pass zero!
  108.    * Be sure to call cleanUp() when you are done with KSpell.
  109.    *
  110.    * If KSpell could not be started correctly, death() is emitted.
  111.    *
  112.    * @param parent      Parent of KSpellConfig dialog..
  113.    * @param caption     Caption of KSpellConfig dialog.
  114.    * @param receiver    Receiver object for the ready(KSpell *) signal.
  115.    * @param slot        Receiver's slot, will be connected to the ready(KSpell *) signal.
  116.    * @param kcs         Configuration for KSpell.
  117.    * @param progressbar Indicates if progress bar should be shown.
  118.    * @param modal       Indicates modal or non-modal dialog.
  119.    * @param type        Type of the document to check
  120.    */
  121.   KSpell(QWidget *parent, const QString &caption,
  122.      QObject *receiver, const char *slot, KSpellConfig *kcs,
  123.      bool progressbar, bool modal, SpellerType type);
  124.  
  125.   /**
  126.    * Returns the status of KSpell.
  127.    *
  128.    * @see spellStatus()
  129.    */
  130.   spellStatus status() const { return m_status; }
  131.  
  132.   /**
  133.    * Cleans up ISpell.
  134.    *
  135.    * Write out the personal dictionary and close ISpell's
  136.    *  stdin.  A death() signal will be emitted when the cleanup is
  137.    *  complete, but this method will return immediately.
  138.    */
  139.   virtual void cleanUp ();
  140.  
  141.   /**
  142.    * Sets the auto-delete flag. If this is set, the KSpell object
  143.    * is automatically deleted after emitting death().
  144.    */
  145.   void setAutoDelete(bool _autoDelete) { autoDelete = _autoDelete; }
  146.  
  147.   /**
  148.    *  Spellchecks a buffer of many words in plain text
  149.    *  format.
  150.    *
  151.    * The @p _buffer is not modified.  The signal done() will be
  152.    *  sent when check() is finished and the argument will be a
  153.    *  spell-corrected version of @p _buffer.
  154.    *
  155.    * The spell check may be stopped by the user before the entire buffer
  156.    *  has been checked.  You can check lastPosition() to see how far
  157.    *  in @p _buffer check() reached before stopping.
  158.    */
  159.  
  160.   virtual bool check (const QString &_buffer, bool usedialog = true);
  161.  
  162.   /**
  163.    * Returns the position (when using check())  or word
  164.    * number (when using checkList()) of
  165.    * the last word checked.
  166.    */
  167.   int lastPosition() const
  168.     { return lastpos;}
  169.  
  170.   /**
  171.    * Spellchecks a list of words.
  172.    *
  173.    * checkList() is more flexible than check().  You could parse
  174.    *  any type
  175.    *  of document (HTML, TeX, etc.) into a list of spell-checkable words
  176.    *  and send the list to checkList().  Sending a marked-up document
  177.    *  to check() would result in the mark-up tags being
  178.    *  spell checked.
  179.    */
  180.   virtual bool checkList (QStringList *_wordlist, bool usedialog = true);
  181.  
  182.   /**
  183.    * Spellchecks a single word.
  184.    *
  185.    * checkWord() is the most flexible function.  Some applications
  186.    *  might need this flexibility but will sacrifice speed when
  187.    *  checking large numbers of words.  Consider checkList() for
  188.    *  checking many words.
  189.    *
  190.    *  Use this method for implementing  "online" spellchecking (i.e.,
  191.    *  spellcheck as-you-type).
  192.    *
  193.    * checkWord() returns @p false if @p buffer is not a single word (e.g.
  194.    *  if it contains white space), otherwise it returns @p true;
  195.    *
  196.    * If @p usedialog is set to @p true, KSpell will open the standard
  197.    *  dialog if the word is not found.  The dialog results can be queried
  198.    *  by using dlgResult() and replacement().
  199.    *
  200.    *  The signal corrected() is emitted when the check is
  201.    *  complete.  You can look at suggestions() to see what the
  202.    *  suggested replacements were.
  203.    */
  204.   virtual bool checkWord (const QString &_buffer, bool usedialog = false);
  205.   bool checkWord( const QString & buffer, bool _usedialog, bool suggest );
  206.  
  207.   /**
  208.    * Hides the dialog box.
  209.    *
  210.    * You'll need to do this when you are done with checkWord();
  211.    */
  212.   void hide ();
  213.  
  214.   /**
  215.    * Returns list of suggested word replacements.
  216.    *
  217.    * After calling checkWord() (an in response to
  218.    *  a misspelled() signal you can
  219.    *  use this to get the list of
  220.    *  suggestions (if any were available).
  221.    */
  222.   QStringList suggestions () const { return sugg; }
  223.  
  224.   /**
  225.    * Gets the result code of the dialog box.
  226.    *
  227.    * After calling checkWord, you can use this to get the dialog box's
  228.    *  result code.
  229.    * The possible
  230.    *  values are (from kspelldlg.h):
  231.    *    @li KS_CANCEL
  232.    *    @li KS_REPLACE
  233.    *    @li KS_REPLACEALL
  234.    *    @li KS_IGNORE
  235.    *    @li KS_IGNOREALL
  236.    *    @li KS_ADD
  237.    *    @li KS_STOP
  238.    *
  239.    */
  240.   int dlgResult () const
  241.     { return dlgresult; }
  242.  
  243.   /**
  244.    * Moves the dialog.
  245.    *
  246.    * If the dialog is not currently visible, it will
  247.    *   be placed at this position when it becomes visible.
  248.    * Use this to get the dialog out of the way of a highlighted
  249.    * misspelled word in a document.
  250.    */
  251.   void moveDlg (int x, int y);
  252.  
  253.   /**
  254.    * Returns the height of the dialog box.
  255.    */
  256.   int heightDlg () const;
  257.   /**
  258.    * Returns the width of the dialog box.
  259.    */
  260.   int widthDlg () const;
  261.  
  262.   /**
  263.    * Returns the partially spellchecked buffer.
  264.    *
  265.    * You might want the full buffer in its partially-checked state.
  266.    */
  267.   QString intermediateBuffer () const {return newbuffer;}
  268.  
  269.   /**
  270.    * Tells ISpell/ASpell to ignore this word for the life of this KSpell instance.
  271.    *
  272.    *  @return false if @p word is not a word or there was an error
  273.    *  communicating with ISpell/ASpell.
  274.    */
  275.   virtual bool ignore (const QString & word);
  276.  
  277.   /**
  278.    * Adds a word to the user's personal dictionary.
  279.    *
  280.    * @return false if @p word
  281.    *  is not a word or there was an error communicating with ISpell/ASpell.
  282.    */
  283.   virtual bool addPersonal (const QString & word);
  284.  
  285.   /**
  286.    * @return the KSpellConfig object being used by this KSpell instance.
  287.    */
  288.   KSpellConfig ksConfig () const;
  289.  
  290.   /**
  291.    * Sets the resolution (in percent) of the progress() signals.
  292.    *
  293.    * E.g. setProgressResolution (10) instructs KSpell to send progress
  294.    *  signals (at most) every 10% (10%, 20%, 30%...).
  295.    * The default is 10%.
  296.    */
  297.   void setProgressResolution (unsigned int res);
  298.  
  299.   /**
  300.    * The destructor instructs ISpell/ASpell to write out the personal
  301.    *  dictionary and then terminates ISpell/ASpell.
  302.    */
  303.   virtual ~KSpell();
  304.  
  305.   /**
  306.    * @deprecated
  307.    * Performs a synchronous spellcheck.
  308.    *
  309.    * This method does not return until spellchecking is done or canceled.
  310.    * Your application's GUI will still be updated, however.
  311.    *
  312.    */
  313.   static int modalCheck( QString& text ) KDE_DEPRECATED;
  314.  
  315.   /**
  316.    * Performs a synchronous spellcheck.
  317.    *
  318.    * This method does not return until spellchecking is done or canceled.
  319.    * Your application's GUI will still be updated, however.
  320.    *
  321.    * This overloaded method uses the spell-check configuration passed as parameter.
  322.    */
  323.   static int modalCheck( QString& text, KSpellConfig * kcs );
  324.  
  325.   /**
  326.    * Call setIgnoreUpperWords(true) to tell the spell-checker to ignore
  327.    * words that are completely uppercase. They are spell-checked by default.
  328.    */
  329.   void setIgnoreUpperWords(bool b);
  330.  
  331.   /**
  332.    * Call setIgnoreTitleCase(true) to tell the spell-checker to ignore
  333.    * words with a 'title' case, i.e. starting with an uppercase letter.
  334.    * They are spell-checked by default.
  335.    */
  336.   void setIgnoreTitleCase(bool b);
  337.  
  338. signals:
  339.  
  340.   /**
  341.    * Emitted whenever a misspelled word is found by check() or
  342.    *   by checkWord().
  343.    *  If it is emitted by checkWord(), @p pos=0.
  344.    *  If it is emitted by check(), then @p pos indicates the position of
  345.    *   the misspelled word in the (original) @p _buffer.
  346.    *   (The first position is zero.)
  347.    *  If it is emitted by checkList(), @p pos is the index to
  348.    *  the misspelled
  349.    *   word in the QStringList passed to checkList().
  350.    *  Note, that @p originalword can be only a word part, if it's
  351.    *  word with hyphens.
  352.    *
  353.    *  These are called _before_ the dialog is opened, so that the
  354.    *   calling program's GUI may be updated. (e.g. the misspelled word may
  355.    *   be highlighted).
  356.    */
  357.   void misspelling (const QString & originalword, const QStringList & suggestions,
  358.             unsigned int pos);
  359.  
  360.   /**
  361.    * Emitted after the "Replace" or "Replace All" buttons of the dialog
  362.    * was pressed, or if the word was
  363.    * corrected without calling the dialog (i.e., the user previously chose
  364.    * "Replace All" for this word).
  365.    *
  366.    * Results from the dialog may be checked with dlgResult()
  367.    *  and replacement().
  368.    *
  369.    * Note, that when using checkList() this signal can occur
  370.    * more then once with same list position, when checking a word with
  371.    * hyphens. In this case @p originalword is the last replacement.
  372.    *
  373.    * @see check()
  374.    */
  375.   void corrected (const QString & originalword, const QString & newword, unsigned int pos);
  376.  
  377.   /**
  378.    * Emitted when the user pressed "Ignore All" in the dialog.
  379.    * This could be used to make an application or file specific
  380.    * user dictionary.
  381.    *
  382.    */
  383.   void ignoreall (const QString & originalword);
  384.  
  385.   /**
  386.    * Emitted when the user pressed "Ignore" in the dialog.
  387.    * Don't know if this could be useful.
  388.    *
  389.    */
  390.   void ignoreword (const QString & originalword);
  391.  
  392.   /**
  393.    * Emitted when the user pressed "Add" in the dialog.
  394.    * This could be used to make an external user dictionary
  395.    * independent of the ISpell personal dictionary.
  396.    *
  397.    */
  398.   void addword (const QString & originalword);
  399.  
  400.   /**
  401.    * Emitted when the user pressed "ReplaceAll" in the dialog.
  402.    */
  403.   void replaceall( const QString & origword ,  const QString &replacement );
  404.  
  405.   /**
  406.    * Emitted after KSpell has verified that ISpell/ASpell is running
  407.    * and working properly.
  408.    */
  409.   void ready(KSpell *);
  410.  
  411.   /**
  412.    * Emitted during a check().
  413.    * @p i is between 1 and 100.
  414.    */
  415.   void progress (unsigned int i);
  416.  
  417.   /**
  418.    * Emitted when check() is done.
  419.    *
  420.    * Be sure to copy the results of @p buffer if you need them.
  421.    *  You can only rely
  422.    *  on the contents of buffer for the life of the slot which was signaled
  423.    *  by done().
  424.    */
  425.   void done (const QString &buffer);
  426.  
  427.   /**
  428.    * Emitted when checkList() is done.
  429.    *
  430.    * If the argument is
  431.    * @p true, then you should update your text from the
  432.    * wordlist, otherwise not.
  433.    */
  434.   void done(bool);
  435.  
  436.   /**
  437.    * Emitted on terminal errors and after clean up.
  438.    *
  439.    * You can delete the KSpell object in this signal.
  440.    *
  441.    * You can check status() to see what caused the death:
  442.    * @li @p Error - KSpell could not start.
  443.    * @li @p Crashed - KSpell encountered an unexpected error during execution.
  444.    * @li @p Finished - Clean up finished.
  445.    */
  446.   void death( );
  447.  
  448.  
  449. protected slots:
  450.   /* All of those signals from KProcIO get sent here. */
  451.   void KSpell2 (KProcIO *);
  452.   void checkWord2 (KProcIO *);
  453.   void checkWord3 ();
  454.   void check2 (KProcIO *);
  455.   void checkList2 ();
  456.   void checkList3a (KProcIO *);
  457.   void checkListReplaceCurrent ();
  458.   void checkList4 ();
  459.   void dialog2 (int dlgresult);
  460.   void check3 ();
  461.   void suggestWord( KProcIO * );
  462.  
  463.   void slotStopCancel (int);
  464.   void ispellExit (KProcess *);
  465.   void emitDeath();
  466.   void ispellErrors (KProcess *, char *, int);
  467.   void checkNext();
  468.  
  469. private slots:
  470.   /**
  471.    * Used for modalCheck().
  472.    */
  473.   void slotModalReady();
  474.  
  475.   /**
  476.    * Used for modalCheck().
  477.    */
  478.   void slotModalDone( const QString & );
  479.  
  480.   /**
  481.    * Used for modalCheck().
  482.    */
  483.   void slotSpellCheckerCorrected( const QString & oldText, const QString & newText, unsigned int );
  484.  
  485.   /**
  486.    * Used for modalCheck().
  487.    */
  488.   void  slotModalSpellCheckerFinished( );
  489.  
  490. signals:
  491.   void dialog3 ();
  492.  
  493. protected:
  494.  
  495.   KProcIO *proc;
  496.   QWidget *parent;
  497.   KSpellConfig *ksconfig;
  498.   KSpellDlg *ksdlg;
  499.   QStringList *wordlist;
  500.   QStringList::Iterator wlIt;
  501.   QStringList ignorelist;
  502.   QStringList replacelist;
  503.   QStringList sugg;
  504.   QTextCodec* codec;
  505.  
  506.   spellStatus m_status;
  507.  
  508.   bool usedialog;
  509.   bool texmode;
  510.   bool dlgon;
  511.   bool personaldict;
  512.   bool dialogwillprocess;
  513.   bool progressbar;
  514.   bool dialogsetup;
  515.   bool autoDelete;
  516.  
  517.   QString caption;
  518.   QString orig;
  519.   QString origbuffer;
  520.   QString newbuffer;
  521.   QString cwword;
  522.   QString dlgorigword;
  523.   QString dlgreplacement;
  524.   QString dialog3slot;
  525.  
  526.   int dlgresult;
  527.   int trystart;
  528.   int maxtrystart;
  529.   int lastpos;
  530.   unsigned int totalpos;
  531.   unsigned int lastline;
  532.   unsigned int posinline;
  533.   unsigned int lastlastline;
  534.   unsigned int offset;
  535.   unsigned int progres;
  536.   unsigned int curprog;
  537.  
  538.   /**
  539.    * Used for modalCheck.
  540.    */
  541.   bool modaldlg;
  542.   static QString modaltext;
  543.   static int modalreturn;
  544.   static QWidget* modalWidgetHack;
  545.  
  546.   int parseOneResponse (const QString &_buffer, QString &word, QStringList &sugg);
  547.   QString funnyWord (const QString & word);
  548.   void dialog (const QString & word, QStringList & sugg, const char* _slot);
  549.   QString replacement () const
  550.     { return dlgreplacement; }
  551.  
  552.   void setUpDialog ( bool reallyusedialogbox = true);
  553.  
  554.   void emitProgress ();
  555.   bool cleanFputs (const QString & s, bool appendCR=true);
  556.   bool cleanFputsWord (const QString & s, bool appendCR=true);
  557.   void startIspell();
  558.   bool writePersonalDictionary();
  559.   void initialize( QWidget *_parent, const QString &_caption,
  560.                    QObject *obj, const char *slot, KSpellConfig *_ksc,
  561.                    bool _progressbar, bool _modal, SpellerType type );
  562.  
  563. private:
  564.   class KSpellPrivate;
  565.   KSpellPrivate *d;
  566. };
  567.  
  568. #endif
  569.